home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / cmds.fmt / rpcgen.man < prev    next >
Text File  |  1989-12-30  |  16KB  |  463 lines
  1.  
  2.  
  3.  
  4. RPCGEN                    User Commands                    RPCGEN
  5.  
  6.  
  7.  
  8. NNAAMMEE
  9.      rpcgen - an RPC protocol compiler
  10.  
  11. SSYYNNOOPPSSIISS
  12.      rrppccggeenn --hh [[--oo _o_u_t_f_i_l_e]] [[_i_n_p_u_t_f_i_l_e]]
  13.      rrppccggeenn --cc [[--oo _o_u_t_f_i_l_e]] [[_i_n_f_i_l_e]]
  14.      rrppccggeenn _i_n_f_i_l_e
  15.      rrppccggeenn [[--ss _t_r_a_n_s_p_o_r_t]]** [[--oo _o_u_t_f_i_l_e] [[_i_n_f_i_l_e]]
  16.  
  17. DDEESSCCRRIIPPTTIIOONN
  18.      _r_p_c_g_e_n is a tool that generates CC code to implement an RPC
  19.      protocol.  The input to _r_p_c_g_e_n is a language with striking
  20.      similarity to CC known as RPCL (Remote Procedure Call
  21.      Language).  _r_p_c_g_e_n operates in four modes.  The first mode
  22.      is used to convert RPCL definitions into CC definitions for
  23.      use as a header file.  The second mode compiles the XDR rou-
  24.      tines required to serialize the protocol described by RPCL.
  25.      The third mode compiles both, leaving the header file in a
  26.      file named _i_n_f_i_l_e with a ..hh extension and the XDR routines
  27.      in _i_n_f_i_l_e with a ..cc extension.  The fourth mode is used to
  28.      compile an RPC server skeleton, so that all you have to do
  29.      is write local procedures that know nothing about RPC in
  30.      order to implement an RPC server.
  31.  
  32.      The input may contain CC-style comments and preprocessor
  33.      directives.  Comments are ignored, while the directives are
  34.      simply stuffed uninterpreted in the output header file.
  35.  
  36.      You can customize some of your XDR routines by leaving those
  37.      data types undefined.  For every data type that is unde-
  38.      fined, _r_p_c_g_e_n will assume that there exists a routine with
  39.      the name `xdr_' prepended to the name of the undefined type.
  40.  
  41. OOPPTTIIOONNSS
  42.      --cc   Compile XDR routines.
  43.  
  44.      --hh   Compile CC data-definitions (a header file)
  45.  
  46.      --oo _o_u_t_f_i_l_e
  47.           Specify the name of the output file.  If none is speci-
  48.           fied, standard output is used (--cc, --hh and --ss modes
  49.           only).
  50.  
  51.      --ss _t_r_a_n_s_p_o_r_t
  52.           Compile a server, using the the given transport.  The
  53.           supported transports are uuddpp and ttccpp. This option may
  54.           be invoked more than once so as to compile a server
  55.           that serves multiple transports.
  56.  
  57. UUSSAAGGEE
  58.  
  59.  
  60.  
  61.  
  62.  
  63. Sprite v1.0               11 March 1986                         1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. RPCGEN                    User Commands                    RPCGEN
  71.  
  72.  
  73.  
  74.      RRPPCCLL SSyynnttaaxx SSuummmmaarryy
  75.      This summary of RPCL syntax, which is used for _r_p_c_g_e_n input,
  76.      is intended more for aiding comprehension than as an exact
  77.      statement of the language.
  78.  
  79.      PPrriimmiittiivvee DDaattaa TTyyppeess
  80.           [ uunnssiiggnneedd ] cchhaarr
  81.           [ uunnssiiggnneedd ] sshhoorrtt
  82.           [ uunnssiiggnneedd ] iinntt
  83.           [ uunnssiiggnneedd ] lloonngg
  84.           uunnssiiggnneedd
  85.           ffllooaatt
  86.           ddoouubbllee
  87.           vvooiidd
  88.           bbooooll
  89.      Except for the added boolean data-type bbooooll, RPCL is identi-
  90.      cal to CC.  _r_p_c_g_e_n converts bbooooll declarations to iinntt declara-
  91.      tions in the output header file (literally it is converted
  92.      to a bbooooll__tt, which has been ##ddeeffiinnee'd to be an iinntt). Also,
  93.      vvooiidd declarations may appear only inside of uunniioonn and pprroo--
  94.      ggrraamm definitions.  For those averse to typing the prefix
  95.      uunnssiiggnneedd, the abbreviations uu__cchhaarr, uu__sshhoorrtt, uu__iinntt and
  96.      uu__lloonngg are available.
  97.  
  98.      DDeeccllaarraattiioonnss
  99.      RPCL allows only three kinds of declarations:
  100.  
  101.      _d_e_c_l_a_r_a_t_i_o_n:
  102.           _s_i_m_p_l_e-_d_e_c_l_a_r_a_t_i_o_n
  103.           _p_o_i_n_t_e_r-_d_e_c_l_a_r_a_t_i_o_n
  104.           _v_e_c_t_o_r-_d_e_c_l_a_r_a_t_i_o_n
  105.  
  106.      _s_i_m_p_l_e-_d_e_c_l_a_r_a_t_i_o_n:
  107.           _t_y_p_e-_n_a_m_e _o_b_j_e_c_t-_i_d_e_n_t
  108.  
  109.      _p_o_i_n_t_e_r-_d_e_c_l_a_r_a_t_i_o_n:
  110.           _t_y_p_e-_n_a_m_e **_o_b_j_e_c_t-_i_d_e_n_t
  111.  
  112.      _v_e_c_t_o_r-_d_e_c_l_a_r_a_t_i_o_n:
  113.           _t_y_p_e-_n_a_m_e _o_b_j_e_c_t-_i_d_e_n_t[[_s_i_z_e]]
  114.  
  115.      (_s_i_z_e can be either an integer or a symbolic constant)
  116.  
  117.      RPCL declarations contain both limitations and extensions
  118.      with respect to CC.  The limitations are that you cannot
  119.      declare multidimensional arrays or pointers-to-pointers in-
  120.      line (You can still declare them though, using ttyyppeeddeeff).
  121.      There are two extensions:
  122.  
  123.           Opaque data is declared as a vector as follows:
  124.  
  125.                ooppaaqquuee _o_b_j_e_c_t-_i_d_e_n_t [[ _s_i_z_e ]]
  126.  
  127.  
  128.  
  129. Sprite v1.0               11 March 1986                         2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. RPCGEN                    User Commands                    RPCGEN
  137.  
  138.  
  139.  
  140.           In the protocol, this results in an object of _s_i_z_e
  141.           bytes. Note that this is _n_o_t the same as a declaration
  142.           of _s_i_z_e characters, since XDR characters are 32-bits.
  143.           Opaque declarations are compiled in the output header
  144.           file into character array declarations of _s_i_z_e bytes.
  145.  
  146.           Strings are special and are declared as a vector
  147.           declaration:
  148.  
  149.                ssttrriinngg _o_b_j_e_c_t-_i_d_e_n_t [[ _m_a_x-_s_i_z_e ]]
  150.  
  151.           If _m_a_x-_s_i_z_e is unspecified, then there is essentially
  152.           no limit to the maximum length of the string. String
  153.           declarations get compiled into the following:
  154.  
  155.                char *_o_b_j_e_c_t-_i_d_e_n_t
  156.  
  157.      TTyyppee DDeeffiinniittiioonnss
  158.      The only way to generate an XDR routine is to define a type.
  159.      For every type _z_e_t_y_p_e you define, there is a corresponding
  160.      XDR routine named _x_d_r__z_e_t_y_p_e.
  161.  
  162.      There are six ways to define a type:
  163.  
  164.      _t_y_p_e-_d_e_f_i_n_i_t_i_o_n:
  165.           _t_y_p_e_d_e_f
  166.           _e_n_u_m_e_r_a_t_i_o_n-_d_e_f
  167.           _s_t_r_u_c_t_u_r_e-_d_e_f
  168.           _v_a_r_i_a_b_l_e-_l_e_n_g_t_h-_a_r_r_a_y-_d_e_f
  169.           _d_i_s_c_r_i_m_i_n_a_t_e_d-_u_n_i_o_n-_d_e_f
  170.           _p_r_o_g_r_a_m-_d_e_f
  171.  
  172.      The first three are very similar to their CC namesakes. CC
  173.      does not have a formal type mechanism to define variable-
  174.      length arrays and XDR unions are quite different from their
  175.      CC counterparts. Program definitions are not really type
  176.      definitions, but they are useful nonetheless.
  177.  
  178.      You may not nest XDR definitions.  For example, the follow-
  179.      ing will cause _r_p_c_g_e_n to choke:
  180.           struct dontdoit {
  181.                struct ididit {
  182.                     int oops;
  183.                } sorry;
  184.                enum ididitagain { OOPS, WHOOPS } iapologize;
  185.           };
  186.  
  187.      Typedefs
  188.      An XDR ttyyppeeddeeff looks as follows:
  189.  
  190.      _t_y_p_e_d_e_f:
  191.           ttyyppeeddeeff _d_e_c_l_a_r_a_t_i_o_n ;;
  192.  
  193.  
  194.  
  195. Sprite v1.0               11 March 1986                         3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. RPCGEN                    User Commands                    RPCGEN
  203.  
  204.  
  205.  
  206.      The _o_b_j_e_c_t-_i_d_e_n_t part of _d_e_c_l_a_r_a_t_i_o_n is the name of the new
  207.      type, whereas the _t_y_p_e-_n_a_m_e part is the name of the type
  208.      from which it is derived.
  209.  
  210.      _E_n_u_m_e_r_a_t_i_o_n _T_y_p_e_s
  211.      The syntax is:
  212.  
  213.      _e_n_u_m_e_r_a_t_i_o_n-_d_e_f:
  214.           eennuumm _e_n_u_m-_i_d_e_n_t {{
  215.                _e_n_u_m-_l_i_s_t
  216.           }};;
  217.  
  218.      _e_n_u_m-_l_i_s_t:
  219.           _e_n_u_m-_s_y_m_b_o_l-_i_d_e_n_t [ == _a_s_s_i_g_n_m_e_n_t ]
  220.           _e_n_u_m-_s_y_m_b_o_l-_i_d_e_n_t [ == _a_s_s_i_g_n_m_e_n_t ] ,, _e_n_u_m-_l_i_s_t
  221.  
  222.      (_a_s_s_i_g_n_m_e_n_t may be either an integer or a symbolic constant)
  223.  
  224.      If there is no explicit assignment, then the implicit
  225.      assignment is the value of the previous enumeration plus 1.
  226.      If not explicitly assigned, the first enumeration receives
  227.      the value 0.
  228.  
  229.      _S_t_r_u_c_t_u_r_e_s
  230.      _s_t_r_u_c_t_u_r_e-_d_e_f:
  231.           ssttrruucctt _s_t_r_u_c_t-_i_d_e_n_t {{
  232.                _d_e_c_l_a_r_a_t_i_o_n-_l_i_s_t
  233.           }};;
  234.  
  235.      _d_e_c_l_a_r_a_t_i_o_n-_l_i_s_t:
  236.           _d_e_c_l_a_r_a_t_i_o_n ;;
  237.           _d_e_c_l_a_r_a_t_i_o_n ;; _d_e_c_l_a_r_a_t_i_o_n-_l_i_s_t
  238.  
  239.      _V_a_r_i_a_b_l_e-_L_e_n_g_t_h _A_r_r_a_y_s
  240.      _v_a_r_i_a_b_l_e-_l_e_n_g_t_h-_a_r_r_a_y-_d_e_f:
  241.           aarrrraayy _a_r_r_a_y-_i_d_e_n_t {{
  242.                uunnssiiggnneedd _l_e_n_g_t_h-_i_d_e_n_t_i_f_e_r ;;
  243.                _v_e_c_t_o_r-_d_e_c_l_a_r_a_t_i_o_n ;;
  244.           }};;
  245.  
  246.      A variable length array definition looks much like a struc-
  247.      ture definition. Here's an example:
  248.           array mp_int {
  249.                unsigned len;
  250.                short val[MAX_MP_LENGTH];
  251.           };
  252.      This is compiled into:
  253.           struct mp_int {
  254.                unsigned len;
  255.                short *val;
  256.           };
  257.           typedef struct mp_int mp_int;
  258.  
  259.  
  260.  
  261. Sprite v1.0               11 March 1986                         4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. RPCGEN                    User Commands                    RPCGEN
  269.  
  270.  
  271.  
  272.      _D_i_s_r_i_m_i_n_a_t_e_d _U_n_i_o_n_s
  273.      _d_i_s_c_r_i_m_i_n_a_t_e_d-_u_n_i_o_n-_d_e_f:
  274.           uunniioonn _u_n_i_o_n-_i_d_e_n_t sswwiittcchh (( _d_i_s_c_r_i_m_i_n_a_n_t-_d_e_c_l_a_r_a_t_i_o_n )) {{
  275.                _c_a_s_e-_l_i_s_t
  276.                [ ddeeffaauulltt :: _d_e_c_l_a_r_a_t_i_o_n ;; ]
  277.           }};;
  278.  
  279.      _c_a_s_e-_l_i_s_t:
  280.           ccaassee _c_a_s_e-_i_d_e_n_t :: _d_e_c_l_a_r_a_t_i_o_n ;;
  281.           ccaassee _c_a_s_e-_i_d_e_n_t :: _d_e_c_l_a_r_a_t_i_o_n ;; _c_a_s_e-_l_i_s_t
  282.  
  283.      _d_i_s_c_r_i_m_i_n_a_n_t-_d_e_c_l_a_r_a_t_i_o_n:
  284.           _d_e_c_l_a_r_a_t_i_o_n
  285.  
  286.      The union definition looks like a cross between a C-union
  287.      and a C-switch.  An example:
  288.           union net_object switch (net_kind kind) {
  289.           case MACHINE:
  290.                struct sockaddr_in sin;
  291.           case USER:
  292.                int uid;
  293.           default:
  294.                string whatisit;
  295.           };
  296.      Compiles into:
  297.           struct net_object {
  298.                net_kind kind;
  299.                union {
  300.                     struct sockaddr_in sin;
  301.                     int uid;
  302.                     char *whatisit;
  303.                } net_object;
  304.           };
  305.           typedef struct net_object net_object;
  306.      Note that the name of the union component of the output
  307.      struct is the same as the name of the type itself.
  308.  
  309.      _P_r_o_g_r_a_m _D_e_f_i_n_i_t_i_o_n_s
  310.      _p_r_o_g_r_a_m-_d_e_f:
  311.           pprrooggrraamm _p_r_o_g_r_a_m-_i_d_e_n_t {{
  312.                _v_e_r_s_i_o_n-_l_i_s_t
  313.           }} == _p_r_o_g_r_a_m-_n_u_m_b_e_r ;;
  314.  
  315.      _v_e_r_s_i_o_n-_l_i_s_t:
  316.           _v_e_r_s_i_o_n
  317.           _v_e_r_s_i_o_n _v_e_r_s_i_o_n-_l_i_s_t
  318.      _v_e_r_s_i_o_n:
  319.           vveerrssiioonn _v_e_r_s_i_o_n-_i_d_e_n_t {{
  320.                _p_r_o_c_e_d_u_r_e-_l_i_s_t
  321.           }} == _v_e_r_s_i_o_n-_n_u_m_b_e_r ;;
  322.      _p_r_o_c_e_d_u_r_e-_l_i_s_t:
  323.           _p_r_o_c_e_d_u_r_e-_d_e_c_l_a_r_a_t_i_o_n
  324.  
  325.  
  326.  
  327. Sprite v1.0               11 March 1986                         5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. RPCGEN                    User Commands                    RPCGEN
  335.  
  336.  
  337.  
  338.           _p_r_o_c_e_d_u_r_e-_d_e_c_l_a_r_a_t_i_o_n _p_r_o_c_e_d_u_r_e-_l_i_s_t
  339.      _p_r_o_c_e_d_u_r_e-_d_e_c_l_a_r_a_t_i_o_n:
  340.           _t_y_p_e-_n_a_m_e _p_r_o_c_e_d_u_r_e-_i_d_e_n_t (( _t_y_p_e-_n_a_m_e )) == _p_r_o_c_e_d_u_r_e-
  341.           _n_u_m_b_e_r ;;
  342.  
  343.      Program definitions look like nothing you've ever seen
  344.      before, so we turn to an example to explain them.  Suppose
  345.      you wanted to create server that could get or set the date.
  346.      It's declaration might look like this:
  347.           program DATE_PROG {
  348.                version DATE_VERS {
  349.                     date DATE_GET(timezone) = 1;
  350.                     void DATE_SET(date) = 2; /* Greenwich mean time */
  351.                } = 1;
  352.           } = 100;
  353.      In the header file, this compiles into the following:
  354.           #define DATE_PROG 100
  355.           #define DATE_VERS 1
  356.           #define DATE_GET 1
  357.           #define DATE_SET 2
  358.      These ddeeffiinnee's are intended for use by the client program to
  359.      reference the remote procedures.
  360.  
  361.      If you are using _r_p_c_g_e_n to compile your server, then there
  362.      are some important things for you to know. The server inter-
  363.      faces to your local procedures by expecting a CC function
  364.      with the same name as that in the program definition, but in
  365.      all lower-case letters and followed by the version number.
  366.      Here is the local procedure that implements DATE_GET:
  367.           date *    /* always returns a pointer to the results */
  368.           date_get_1(tz)
  369.                timezone *tz;  /* always takes a a pointer to the arguments */
  370.           {
  371.                static date d; /* must be static! */
  372.  
  373.                /*
  374.                 * figure out the date
  375.                 * and store it in d
  376.                 */
  377.                return(&d);
  378.           }
  379.      The name of the routine is the same as the ##ddeeffiinnee'd name,
  380.      but in all lower case letters and followed by the version
  381.      number. XDR will recursively free the argument after getting
  382.      the results from your local procedure, so you should copy
  383.      from the argument any data that you will need between calls.
  384.      However, XDR neither allocates nor frees your results. You
  385.      must take care of their storage yourself.
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393. Sprite v1.0               11 March 1986                         6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. RPCGEN                    User Commands                    RPCGEN
  401.  
  402.  
  403.  
  404.      MMaakkee IInnffeerreennccee RRuulleess FFoorr CCoommppiilliinngg XXDDRR HHeeaaddeerrss
  405.  
  406.      It is possible to set up suffix transformation rules in
  407.      _m_a_k_e(1) for compiling XDR routines and header files.  The
  408.      convention is that RPCL protocol files have the extension
  409.      ..xx.  The _m_a_k_e rules to do this are:
  410.           .SUFFIXES: .x
  411.           .x.c:
  412.                rpcgen -c $< -o $@
  413.  
  414.           .x.h:
  415.                rpcgen -h $< -o $@
  416.  
  417. SSEEEE AALLSSOO
  418.      _R_e_m_o_t_e _P_r_o_c_e_d_u_r_e _C_a_l_l: _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e and _E_x_t_e_r_n_a_l _D_a_t_a
  419.      _R_e_p_r_e_s_e_n_t_a_t_i_o_n: _P_r_o_t_o_c_o_l _S_p_e_c_i_f_i_c_a_t_i_o_n in _N_e_t_w_o_r_k_i_n_g _o_n _t_h_e
  420.      _S_u_n _W_o_r_k_s_t_a_t_i_o_n
  421.  
  422. BBUUGGSS
  423.      Name clashes can occur when using program definitions, since
  424.      the apparent scoping does not really apply. Most of these
  425.      can be avoided by giving unique names for programs, ver-
  426.      sions, procedures and types.
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459. Sprite v1.0               11 March 1986                         7
  460.  
  461.  
  462.  
  463.